API（Recommend）

概要

このドキュメントでは、サーバーサイド統合のためのRecommend APIの使用方法について説明します。当社のAPIはRESTに似ており、すべてのレスポンスはJSON形式で返されます。また、クロスオリジンリソース共有にも対応しており、クライアントサイドのWebアプリケーションから安全に操作することができます。（ただし、秘密のAPIキーを公開されたWebサイトのクライアントサイドコードに露出させないでください）。

このガイドは以下の前提を想定しています：

• Webまたはアプリケーション開発の経験があること。

• REST APIについての理解があること。

• JSONデータのデシリアライズおよび利用方法を理解していること。

• ECサイトおよびアプリケーションに関する基本的な知識があること。

• Recommendについてすでに知っていること。

利点

• サーバーサイド統合では、Algonomyのp13n.js（パーソナライズ用メディアライブラリ）を各Webページに読み込む必要がありません。

• APIは、スタンドアロンのコールセンターやPOSアプリケーションなど、Webベースでないアプリケーションでも使用できます。

• レスポンスは、Webブラウザ内で実行されないプログラミング言語によるサーバーサイドコードで処理できます。これは、追加のリソースやバックエンドシステムが必要な場合に有効です。たとえば、製品の価格が頻繁に変更される場合、recsForPlacements APIのレスポンスで返された製品IDを使用して、製品管理システムまたはデータベースからリアルタイム価格を取得し、それをWebサイト上に表示することができます。

前提条件

• サーバーサイドのレスポンス処理コードが可視化できないため、Algonomyの統合コンサルタントがデバッグ支援を行うのが難しくなります。

• レスポンス形式の制御が少なくなります。recsForPlacements APIを使用して推奨を要求する場合、推奨された製品に関連するほとんどのデータ（カテゴリや属性など）が返されます。リクエスト内のパラメーターを使ってレスポンスのサイズを削減することはできますが、JSONレスポンスの正確なフォーマットやレイアウトは、クライアントサイド統合のようにカスタマイズすることはできません。

Recommend API

Recommendから推奨を取得するためのメインAPIはrecsForPlacements APIです。本ドキュメントの残りの部分では、このAPIの使用方法に焦点を当てます。

サイト上のページを統合する最初のステップは、リクエストしたいWebページのタイプ（またはアプリケーションの一部）に最も近いページタイプを決定することです。ページタイプはパーソナライズプロセスにおいて重要な役割を果たします。これは、Experience Optimizerがリアルタイムで顧客の購買意欲に影響を与える可能性が高い推奨戦略を判断する際のコンテキストを設定するためです。各ページタイプには必須パラメーターがあります。以下に示すのは、よくあるECサイトのページタイプに対して、サーバーサイド統合の例としてのrecsForPlacement API呼び出しです： 

• ホームページ

• カートに追加ページ

• カートページ

• レジストリに追加ページ

• ブランドページ

• カテゴリページ

• エラーページ

• 汎用ページ

• アイテムページ

• パーソナルページ

• 購入完了ページ

• 検索ページ

• ウィッシュリストページ（近日公開）

recsForPlacementsリファレンスページで、入力パラメーターの包括的な一覧をご覧ください。

関連API

recsForPlacements APIと一緒に使用する、または代替として使用可能な他の関連APIもいくつか存在します。これには、製品カタログの更新や、Recommendにユーザー情報を照会するためのAPIなどが含まれます。これらのAPIのほとんどはこのドキュメントの範囲外ですが、他のAPIの一覧はPersonalization Cloud: APIsリファレンスページに掲載されています。

サーバーサイド実装用APIエンドポイント

本番環境

本番環境で推奨を取得するには以下のURLを使用してください：

https://recs.richrelevance.com/rrserver/api/rrPlatform/recsForPlacements

統合環境

QA、ステージング、または開発環境から推奨を取得するには、以下のURLを使用してください。この方法により、本番環境に影響を与えずに（マーチャンダイジングや戦略ルールなどの）変更をテストできます。

https://integration.richrelevance.com/rrserver/api/rrPlatform/recsForPlacements

IMPORTANT: 変更を加えた後は、Algonomyのコンサルタントと連携して、バニティURLをhttps://[customername].algorecs.comまたはhttps://recs.algorecs.comに更新してください。API呼び出しおよび計測メカニズムで使用されるその他のパラメーターはすべて同じままで構いません。

クライアントサイド実装用APIエンドポイント

Personalization CloudへWebブラウザから直接APIリクエストを送信することは推奨されていません。APIゲートウェイを使用したリバースプロキシ方式で、自社ドメインを通じてAPIリクエストをルーティングしてください。APIゲートウェイのリバースプロキシ方式の詳細については、API Reverse Proxy Domainを参照してください。

JavaScriptソリューションの詳細については、クライアントサイド統合ガイドを参照してください。もし、WebブラウザからPersonalization Cloudへ直接API呼び出しを実装している場合は、APIエンドポイントで新しい専用のデータキャプチャドメインであるhttps://recs.algorecs.comに更新することを推奨します。

本番環境

本番環境で推奨を取得するには以下のURLを使用してください：

https://recs.algorecs.com/rrserver/api/rrPlatform/recsForPlacements

統合環境

QA、ステージング、または開発環境から推奨を取得するには、以下のURLを使用してください。この方法により、本番環境に影響を与えずに（マーチャンダイジングや戦略ルールなどの）変更をテストできます。

https://integration.algorecs.com/rrserver/api/rrPlatform/recsForPlacements

IMPORTANT: 変更を加えた後は、Algonomyのコンサルタントと連携して、バニティURLを https://[customername].algorecs.com または https://recs.algorecs.com に更新してください。

API呼び出しおよび計測メカニズムで使用されるその他のパラメーターはすべて同じままで構いません。

認証

APIリクエストにAPIキーおよびAPIクライアントキーを含めて認証を行います。APIキーの管理はダッシュボードで行うことができます。APIキーには多くの権限があるため、必ず安全に保管してください。GitHub、検索可能なpastebinサイト、クライアントサイドコードなど、公開されている場所では秘密のAPIキーを共有しないでください。

JSON-P コールバック

recsForPlacements API 呼び出しのレスポンスを JSON 関数でラップするには、jsonp フラグをオンにして、jcp パラメーターに JavaScript のコールバック関数を指定します。例：?jsonp=true&jcp=myCallback

JSON-P はクロスドメインの問題を回避するためによく使用されます。たとえば、Webブラウザ内で動作するアプリケーションでAPIから返された推奨結果を利用する場合に有用です。ただし、Webベースのアプリケーションでは、recsForPlacements API の代わりにCore JSON Integrationの使用を推奨します。

クライアントエラー

不正なパラメーター値の指定などにより発生したほとんどのエラーは、HTTPステータス 200 OK として返され、レスポンスボディにエラー内容が記述されます。そのため、エラーの詳細を確認するにはレスポンスの解析が必要です。

{
  "errormessage": "recsForPlacements API リクエストの処理中に内部エラーが発生しました",
  "status": "error"
}

リクエスト処理中に内部エラー（稀）が発生した場合は、HTTP 500（5xx）レスポンスが返されることがあります。

パラメーター

以下は、ページタイプ別に recsForPlacements API リクエスト時に含める必要があるパラメーターの説明です。すべてのパラメーターの一覧については、recsForPlacementsリファレンスをご参照ください。

共通必須パラメーター

以下のパラメーターは、ページタイプに関係なく recsForPlacements API に必要です。

共通オプションパラメーター

以下のパラメーターは必須ではありませんが、実用的であり、ベストプラクティスとして使用することが推奨されます。

ページタイプ別のパラメーター

上記の共通パラメーターに加え、以下の表では各ページタイプに必要な追加パラメーターについて説明しています。

レスポンス例

レスポンスは、現在のユーザー向けに推奨された商品オブジェクトのリストを含むJSONオブジェクトです。以下は、靴カテゴリから2つの商品が推奨された例です：

レスポンスヘッダー

HTTP/1.1 200 OK
Date: Thu, 21 Jun 2018 22:16:47 GMT
Set-Cookie: m=1;Path=/
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: application/json;charset=utf-8
Vary: Accept-Encoding
Content-Length: 2390
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS, POST
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Content-Type, Access-Control-Request-Method, Access-Control-Request-Headers, Authorization, X-Requested-With

レスポンスボディ

{
  "rcs": "eF5j4cotK8lM4TMzsNA11DVkKU32MEkyBAJjM11jYzMzXRNTozRdA0sgYZxiammQaGJmZmaaDABuTQ0O",
  "placements": [
    {
      "htmlElementId": "home_page_0",
      "placementType": "home_page",
      "strategyMessage": "Shop Top Sellers",
      "html": "",
      "placement": "home_page.rr1",
      "recommendedProducts": [
        {
          "clickURL": "https://integration.richrelevance.com/rrserver/apiclick?a=showcaseparent&cak=776cdd80331919e7&ct=http%3A%2F%2Flabs.richrelevance.com%2Fstorre%2Fcatalog%2Fproduct%2Fview%2Fsku%2F22127002&vg=4b121136-3366-452f-092f-3d590a46665c&stid=126&pti=9&pa=11339&pos=0&p=22127002&channelId=776cdd80331919e7&s=827ccb0eea8a706c4c34a16891f84e7b&u=12345&mvtId=-1&mvtTs=1529712166361",
          "regionPriceDescription": "",
          "salePriceRangeCents": [
            1,
            1
          ],
          "rating": 3.884,
          "numReviews": 0,
          "priceRangeCents": [
            1,
            1
          ],
          "categoryIds": [
            "Electronics",
            "Electronics.Computers",
            "Electronics.Computers.Tablet PCs"
          ],
          "clickTrackingURL": "https://integration.richrelevance.com/rrserver/apiclick?a=showcaseparent&cak=776cdd80331919e7&vg=4b121136-3366-452f-092f-3d590a46665c&stid=126&pti=9&pa=11339&pos=0&p=22127002&channelId=776cdd80331919e7&s=827ccb0eea8a706c4c34a16891f84e7b&u=12345&mvtId=-1&mvtTs=1529712166361",
          "salePriceCents": 1,
          "regionalProductSku": "22127002",
          "imageURL": "http://labs.richrelevance.com/storre/media/catalog/product/n/e/nextbook-7quot-tablet-with-8gb-memory-with-google-mobile-services-73fbdb1640b18e99695aa87c7da712f5.jpg",
          "name": "\"Nextbook 7\\\" Tablet with 8GB Memory with Google Mobile Services\"",
          "genre": "default",
          "isRecommendable": true,
          "priceCents": 6900,
          "attributes": {
            "MktplcInd": [
              "W"
            ],
            "Clearance": [
              "N"
            ],
            "97CentShipping": [
              "N"
            ],
            "Rollback": [
              "N"
            ],
            "Online": [
              "Y"
            ],
            "ListPrice": [
              "79"
            ],
            "AddToCart": [
              "Y"
            ],
            "IsReducedPrice": [
              "N"
            ],
            "IsSubmap": [
              "N"
            ],
            "S2S": [
              "Y"
            ]
          },
          "id": "22127002",
          "categories": [
            {
              "hasChildren": false,
              "name": "Electronics",
              "childCategories": [],
              "ancestorCategories": [],
              "id": "Electronics",
              "isActive": false
            },
            {
              "hasChildren": false,
              "name": "Computers",
              "childCategories": [],
              "ancestorCategories": [],
              "id": "Electronics.Computers",
              "isActive": false
            },
            {
              "hasChildren": false,
              "name": "Tablet PCs",
              "childCategories": [],
              "ancestorCategories": [],
              "id": "Electronics.Computers.Tablet PCs",
              "isActive": false
            }
          ],
          "productURL": "http://labs.richrelevance.com/storre/catalog/product/view/sku/22127002",
          "brand": "Nextbook"
        }
      ]
    }
  ],
  "viewGuid": "4b121136-3366-452f-092f-3d590a46665c",
  "status": "ok"
}

リソース

以下は、recsForPlacements API への正常な呼び出しによって返されるリソース（JSONオブジェクト）の詳細な説明です。

レスポンスオブジェクト

レスポンスオブジェクトには、recsForPlacements API 呼び出しで要求された各プレースメントに対応するプレースメントオブジェクトが含まれます。

プレースメントオブジェクト

プレースメントオブジェクトは、そのプレースメントに適用された戦略によって決定された1つ以上の推奨商品を含みます。

商品オブジェクト

商品オブジェクトは、あるプレースメントに対して推奨された個々の商品を表します。

属性オブジェクト

商品オブジェクトには、1つ以上の属性オブジェクトを含めることができます。これらの属性は、製品カタログフィードおよび/またはカタログ更新APIを介してRecommendに渡されます。

* これらは、製品カタログフィードおよび/またはカタログ更新APIで定義されます。

カテゴリオブジェクト

商品オブジェクトには、1つ以上のカテゴリオブジェクトを含めることができます。カテゴリは、製品カタログフィードおよび/またはカタログ更新APIで定義されます。